CSS Custom Highlight API: Mastering Multi-Range Text Selection for Dynamic UIs

The CSS Custom Highlight API is a powerful new tool for web developers that allows for unprecedented control over text selection and highlighting within web applications. Unlike the basic browser selection capabilities, this API enables developers to define custom highlight styles and manage multiple selection ranges programmatically. This opens up a world of possibilities for creating rich, interactive, and accessible user interfaces. This guide provides a comprehensive overview of the API, exploring its capabilities, use cases, and implementation details, all with a global perspective.

Understanding the Basics of the CSS Custom Highlight API

Before diving into complex scenarios, it's essential to grasp the fundamental concepts of the API. At its core, the CSS Custom Highlight API introduces several new CSS pseudo-elements, including:

• ::selection: Represents the portion of a document that has been selected by the user. This has been available for a long time, allowing basic styling of text selections.
• ::highlight: A more general pseudo-element for applying styles to highlighted ranges. This is the key to the new API's power. You can now create named highlights and apply custom styling to each.
• ::target-text: Represents the portion of a document targeted by a URI fragment (e.g., #section-title). It allows you to style the section of the page that the user scrolled to via a link.
• ::spelling-error: Represents text identified by the user agent as containing spelling errors. Offers styling control over spelling error indicators.
• ::grammar-error: Represents text identified by the user agent as containing grammatical errors. Offers styling control over grammar error indicators.

The ::highlight pseudo-element is the workhorse of the API. It allows you to define named highlights in CSS and then apply those highlights to specific ranges of text using JavaScript.

Key Concepts: Ranges and Highlights

The API revolves around the concepts of ranges and highlights:

• Range: A contiguous section of text within the document. Represented by the Range object in JavaScript.
• Highlight: A named style applied to one or more ranges. Defined in CSS using the ::highlight(highlight-name) pseudo-element and manipulated through the Highlight and HighlightRegistry APIs in JavaScript.

Think of it this way: a range is the 'what' (the text you want to highlight), and the highlight is the 'how' (the style you want to apply).

Setting up Custom Highlights with CSS

The first step is to define your custom highlight styles in CSS. You do this using the ::highlight() pseudo-element.

            
::highlight(search-result) {
  background-color: yellow;
  color: black;
}

::highlight(important-term) {
  background-color: lightblue;
  font-weight: bold;
}

            

              
                Copy
              
            
          

In this example, we've defined two custom highlight styles: search-result and important-term. The search-result highlight will apply a yellow background with black text, while the important-term highlight will use a light blue background and bold the text. You can define any CSS properties you want within these highlight styles.

Managing Highlights with JavaScript

Once you've defined your highlight styles in CSS, you can use JavaScript to apply them to specific ranges of text. The Highlight and HighlightRegistry APIs provide the tools for this.

The HighlightRegistry

The HighlightRegistry is a global object that manages all the highlights in the document. You can access it through the CSS interface:

            
const highlightRegistry = CSS.highlights;

            

              
                Copy
              
            
          

Creating Highlights

To create a highlight, you use the Highlight constructor:

            
const highlight = new Highlight();

            

              
                Copy
              
            
          

Initially, a highlight has no ranges associated with it. You need to add ranges to the highlight using the addRange() method.

Adding Ranges to a Highlight

To add a range to a highlight, you first need to create a Range object. You can do this using the document.createRange() method:

            
const range = document.createRange();
range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);

highlight.addRange(range);

            

              
                Copy
              
            
          

Where:

• startNode: The DOM node where the range starts.
• startOffset: The character offset within the startNode where the range starts.
• endNode: The DOM node where the range ends.
• endOffset: The character offset within the endNode where the range ends.

Example: Highlighting Search Results

Let's say you have a block of text and you want to highlight all occurrences of a search term. Here's how you could do it:

            
function highlightSearchResults(searchTerm, element) {
  const text = element.textContent;
  let index = text.indexOf(searchTerm);

  if (index === -1) {
    return; // Search term not found
  }

  const highlight = new Highlight();

  while (index !== -1) {
    const range = document.createRange();
    range.setStart(element.firstChild, index);
    range.setEnd(element.firstChild, index + searchTerm.length);
    highlight.addRange(range);
    index = text.indexOf(searchTerm, index + 1);
  }

  // Apply the 'search-result' highlight style
  highlightRegistry.set('search-result', highlight);
}

const contentElement = document.getElementById('content');
highlightSearchResults('example', contentElement);

            

              
                Copy
              
            
          

This code snippet finds all occurrences of the word "example" within the element with the ID "content" and applies the search-result highlight style to them.

Removing Ranges and Highlights

You can remove ranges from a highlight using the deleteRange() method:

            
highlight.deleteRange(range);

            

              
                Copy
              
            
          

You can also remove all ranges from a highlight using the clear() method:

            
highlight.clear();

            

              
                Copy
              
            
          

To remove a highlight entirely, you can use the delete() method of the HighlightRegistry:

            
highlightRegistry.delete('search-result');

            

              
                Copy
              
            
          

Advanced Use Cases and Considerations

The CSS Custom Highlight API is a powerful tool that can be used in a variety of advanced scenarios.

Collaborative Editing

In collaborative editing applications, you can use the API to highlight the changes made by different users. Each user could have their own custom highlight style, allowing you to easily see who made which changes. For example, a collaborative document editor used by teams in multiple countries could use different highlight colors to represent edits from team members in Japan, Germany, and Brazil.

Code Editors

Code editors can leverage the API for syntax highlighting. Different syntax elements (e.g., keywords, operators, comments) can be assigned different highlight styles. Modern code editors often have complex syntax highlighting rules, and this API allows for more precise and customizable control than traditional methods.

Accessibility

The API can be used to improve accessibility. For example, you could highlight the currently focused element or the text that is being read by a screen reader. Remember to ensure sufficient color contrast between the highlight background and text color for users with visual impairments. The WCAG (Web Content Accessibility Guidelines) provide specific guidelines on color contrast ratios.

Internationalization (i18n) Considerations

When using the API in multilingual applications, be mindful of the following:

• Text Direction: Ensure that your highlight styles work correctly with both left-to-right (LTR) and right-to-left (RTL) languages.
• Word Boundaries: Different languages have different rules for word boundaries. Be sure to use appropriate word boundary detection algorithms when highlighting words or phrases.
• Character Sets: The API supports Unicode, so you can highlight text in any language.

For instance, when highlighting search terms in Arabic (an RTL language), ensure the highlight visually reflects the correct text direction. Similarly, when highlighting keywords in Japanese, which doesn't use spaces between words, you'll need to use appropriate morphological analysis to identify word boundaries.

Performance Considerations

While the API is powerful, it's important to be mindful of performance. Creating and managing a large number of highlights can impact performance, especially in large documents. Consider these tips:

• Optimize Range Creation: Creating Range objects can be expensive. Reuse existing ranges whenever possible.
• Batch Updates: When making multiple changes to highlights, batch them together into a single update to minimize reflows.
• Lazy Loading: Only highlight the text that is currently visible to the user. Load additional highlights as the user scrolls.
• Virtualization: For very large documents, consider using virtualization techniques to only render the visible portion of the document.

Practical Examples and Code Snippets

Example 1: Dynamic Keyword Highlighting

This example demonstrates how to dynamically highlight keywords in a text based on user input. Imagine a user typing a search query into a search box; the highlighted keywords update in real-time.

            


  This is some example text.  It contains keywords that we want to highlight.  We will highlight the keywords based on user input.


            

              
                Copy
              
            
          

            
const keywordInput = document.getElementById('keyword-input');
const textContainer = document.getElementById('text-container');

keywordInput.addEventListener('input', () => {
  const keyword = keywordInput.value.trim();
  if (keyword) {
    highlightKeyword(keyword, textContainer);
  } else {
    clearHighlights(textContainer);
  }
});

function highlightKeyword(keyword, element) {
  clearHighlights(element);
  const text = element.textContent;
  let index = text.indexOf(keyword);

  if (index === -1) {
    return;
  }

  const highlight = new Highlight();

  while (index !== -1) {
    const range = document.createRange();
    range.setStart(element.firstChild, index);
    range.setEnd(element.firstChild, index + keyword.length);
    highlight.addRange(range);
    index = text.indexOf(keyword, index + 1);
  }

  CSS.highlights.set('dynamic-keyword', highlight);
}

function clearHighlights(element) {
  CSS.highlights.delete('dynamic-keyword');
}

            

              
                Copy
              
            
          

            
::highlight(dynamic-keyword) {
  background-color: rgba(255, 165, 0, 0.5); /* Semi-transparent orange */
  color: black;
}

            

              
                Copy
              
            
          

Example 2: Implementing a "Find All" Feature

This example simulates a "Find All" feature, similar to those found in text editors and IDEs. All occurrences of a search term are highlighted simultaneously.

            


  This document contains multiple instances of the search term. The search term will be highlighted throughout the document.
  This is a second instance of the search term. Here's another search term.


            

              
                Copy
              
            
          

            
const searchTermInput = document.getElementById('search-term');
const documentContent = document.getElementById('document-content');

searchTermInput.addEventListener('input', () => {
  const searchTerm = searchTermInput.value.trim();
  if (searchTerm) {
    findAll(searchTerm, documentContent);
  } else {
    clearFindAllHighlights(documentContent);
  }
});

function findAll(searchTerm, element) {
  clearFindAllHighlights(element);
  const text = element.textContent;
  let index = text.indexOf(searchTerm);
  const highlight = new Highlight();

  while (index !== -1) {
    const range = document.createRange();
    range.setStart(element.firstChild, index);
    range.setEnd(element.firstChild, index + searchTerm.length);
    highlight.addRange(range);
    index = text.indexOf(searchTerm, index + 1);
  }

  CSS.highlights.set('find-all', highlight);
}

function clearFindAllHighlights(element) {
  CSS.highlights.delete('find-all');
}

            

              
                Copy
              
            
          

            
::highlight(find-all) {
  background-color: #90EE90; /* LightGreen */
  color: black;
}

            

              
                Copy
              
            
          

Browser Compatibility and Polyfills

The CSS Custom Highlight API is a relatively new feature, so browser compatibility may vary. As of late 2024, it enjoys good support in modern browsers like Chrome, Firefox, Safari, and Edge. However, it's essential to check the latest browser compatibility data on websites like "Can I use..." to ensure your target audience can use your features. If you need to support older browsers, you might explore polyfills or alternative approaches that mimic the functionality of the API, though they may not offer the same level of performance or fidelity.

The Future of Text Selection and Highlighting

The CSS Custom Highlight API represents a significant step forward in web development, providing developers with granular control over text selection and highlighting. As the API matures and browser support improves, we can expect to see even more innovative uses of this technology. From advanced text editors to collaborative document platforms, the possibilities are endless. This API allows for a richer, more interactive, and more accessible user experience. Consider how this can be used to enhance user experiences in everything from international news sites to online language learning platforms.

Conclusion

The CSS Custom Highlight API is a powerful tool for creating dynamic and interactive user interfaces. By understanding the basic concepts of ranges, highlights, and the HighlightRegistry, you can leverage this API to build compelling user experiences that were previously difficult or impossible to achieve. As you explore this API, remember to consider accessibility, internationalization, and performance to ensure that your applications are usable and performant for a global audience. With its flexibility and control, the CSS Custom Highlight API is poised to become an essential part of the modern web developer's toolkit.